Microsoft Entra ID integration

Azure AD is now Microsoft Entra ID. Microsoft has renamed Azure AD as Microsoft Entra ID. However, this does not lead to a disruption in your deployment, configuration or integration. They will continue to function as they did previously.

TheBMSintegration with Microsoft Entra ID enables contacts and users to be automatically created and synced based on the users that are defined in one or more Active Directory tenants. Primary integration is with Microsoft Entra ID, but it can be used with on-premise Active Directory via Microsoft Entra Connect. Additionally, Active Directory records will propagate to IT Glue if that integration is enabled.

Microsoft Entra ID to BMS mapping overview

  • Mapping of users from Active Directory to BMS is based on Security Group. If a user belongs to more than one Security Group, the order value determines which record has precedence. The lowest order value has precedence. If two groups have the same order value, the oldest group has precedence.
  • BMS will match Active Directory records to existing records based on email address. If the email address in the AD record is found in BMS, that record will be merged. If the email address is not found, a new record will be created in BMS. The record identifier for contacts created locally inBMS does not change. Therefore, no linkages to tickets or other record types are affected.
  • After initial sync, any updates to records in Active Directory will automatically be pushed to BMS. It takes up to three minutes for changes in Active Directory to be synced with BMS.
  • Any changes to a synced record in BMS will persist until the record is changed in Active Directory, at which point the local changes will be overwritten.
  • Deleted records in Active Directory will be deactivated in BMS, but not deleted.
  • The table below indicates the field mapping between Active Directory and BMS. When a field in the AD user record is updated, whether mapped or not, AD sends a notification to BMS to update the record. However, only the fields listed below are consumed.

Field Mapping Table
AD Field BMS Field

First Name

 First Name
Last Name Last Name
User Principal Name Username 
Source Field
Microsoft Account Email
Microsoft Entra ID Email
External AD Email
Email
Office Phone
Type Field
Employee Phone
Contact Phone Number
(Default Phone Type)
Job Title Job Title

NOTE  When you enable AD sync, username in BMS will be without the @domainname.

Microsoft Entra ID setup

Kaseya BMS accesses the user records in your Microsoft Entra tenant via the Microsoft Graph API. In order to do this, BMS must be authenticated and authorized by the Microsoft Identity Platform using the OAuth 2.0 standard.

IMPORTANT  Please review the tips below before you proceed with your actions. The Microsoft Entra ID integration works only with P1 and P0 licenses. It does not work with the free version.

Tips

  • Your Active Directory is always the source of truth. If you have a user user@mymsp.com as part of BMS HR > Employees, and if your AD has this mapped as a client portal user, AD will sync existing employee as a client portal user in BMS.
  • The user will be archived from HR and a new entry for the client portal will be created in CRM. The archived user will have user_Archived in their username and user@mymsp.com_Archived in the email address.
  • As both these user types are part of HR, one of them will have to be archived and the sync archives the one in employees as the mapping rules set are for the client portal. 
  • The system cannot have two different logins for one user. This will trigger an archive on the user part of the employee. BMS then creates another user and makes it a client portal user.
  • If this was accidental, this has to be fixed in the AD. Make any false change to the user, like editing the last name, job title, etc. so that the AD can push this change to BMS in real time.  
  • If the archived user had relational data, like tickets or invoices, the user cannot be renamed or deleted from the database.

For Microsoft Entra child tenants, the setup will work if the parent tenant has access to the child tenants, where the admin can add users from child tenants to the Users and Groups Permissions of the Enterprise Application on the parent tenant.

Step 1: BMS registration

In this part of the setup, you will register BMS with your Microsoft Entra tenant. For background, see the this section of the Microsoft Identity Platform documentation.

  1. Navigate to your Microsoft Entra tenant.
  2. Note your tenant domain name. You will need this later.

    The domain name is found as Current Directory in your Microsoft directory subscription details. If you do not have a fully qualified domain name and are using the Microsoft sub-domain it would be yoursubdomain.onmicrosoft.com. Refer How to Find My Microsoft Entra Tenant Name

  3. Under Manage, click App Registration.
  4. Click +New Registration.
  5. Name the application, e.g., Kaseya BMS.
  6. Under Supported Account Types, make BMS multi-tenant. You can select option beginning with Accounts in any organizational directory...
  7. Enter the following Redirect URI:  https://<server-base-url>/OAuth/IntegrationCallback.aspx
    1. US server: https://bms.kaseya.com/OAuth/IntegrationCallback.aspx
    2. UK server: https://bmsemea.kaseya.com/OAuth/IntegrationCallback.aspx
    3. APAC server: https://bmsapac.kaseya.com/OAuth/IntegrationCallback.aspx
    4. Vorex: https://www.vorexlogin.com/OAuth/IntegrationCallback.aspx
  8. On the Application Overview page, note the Application ID.

mceclip10.png

Step 2: BMS permissions

In this part of the setup, you will grant BMS permissions to access the Microsoft Graph API as the signed in BMSuser. For background, see this section of the Microsoft Identity Platform documentation.

  1. Navigate to App Registrations, and select your app, e.g., Kaseya BMS.
  2. Under Manage, select API Permissions.
  3. Under Configured Permissions, select Add a Permission.
  4. From the right side panel, select Microsoft Graph API.
  5. Select Delegated Permissions. For background on permission types, see this section of the Microsoft Identity Platform documentation.
  6. Select the following permissions, and then click Add Permissions.
    • Directory.Read.All
    • Group.Read.All
    • User.Read
    • User.Read.All
  7. Click Grant Admin Consent... and accept. For background on this button, see this section of the Microsoft Entra ID documentation.

mceclip9.png

Step 3: BMS credentials

BMS needs its own credentials in order to authenticate itself with the Microsoft Identity Platform. In this part of the setup, you will generate a client ID and secret key for BMS. For background, see this section of the Microsoft Identity Platform documentation.

  1. Begin from the last screen of the previous section.
  2. Under Manage, click Certificates & Secrets.
  3. Click +New Client Secret.
  4. Complete the form that pops up.
  5. Copy the secret key to a notepad for use in the next section. This section gets hashed out once saved. Do not skip copying the values.
    • The data in the Value column should be copied.

Step 4: BMS setup

Employee Defaults

In this part of the setup, you will set the mapping rules for employee records. Every employee record in BMS has certain mandatory fields. If this field is not set in the Active Directory record, you must decide what value the field should default to.

  1. Navigate to Admin > My Company > Auth & Provision.
  2. At the bottom of the page, select the Micosoft Entra ID Sync radio button.
  3. Complete the Employee Defaults section.
  4. Click Save.

mceclip7.png

Microsoft Entra Connection

In this part of the setup, you will plug in details of your Microsoft Entra ID configuration into BMS. From Microsoft Entra, you will need the following:

  1. Click Add under the Microsoft Entra Connections tab.
  2. Enter the Tenant Domain Name, Application ID, and Application Key from your Microsoft Entra ID configuration.
    • The directory name is your tenant name or the ID. Both of them work for this initial connection. Mapping rules however need only the ID. 
    • Application ID 
    • Application Key (BMS) = Secret Value 
  3. Click Microsoft Entra Connect and authenticate using OAuth. 
    • If you see the permission required window, check the Consent on behalf of your organization box and Accept. 

mceclip11.png

mceclip1.png

mceclip0.png

mceclip0.png

The Microsoft Entra ID sync system will auto-reconnect after certain amount of failures after a period of 120 seconds.

Mapping Rules

ALERT  Once mapping rules are set and sync is initiated, BMS users will be associated with the new security group coming from the AD. Existing user access will beoverridden with what is specified in the AD. Mapping rules should be set correctly as this controls the login access and module permissions for the synced users.  Any synced user with no rules would have no access to BMS. The root user is exempted from access revoke when this happens.

In this part of the setup, you will specify the groups you want to sync between BMS and Microsoft Entra ID. From Microsoft Entra, you will need:

  • Tenant Domain Name
  • Group Object ID
  1. In Microsoft Entra, navigate to your Active Directory tenant, and under Manage, click Groups.
  2. Copy the Group Object ID for the groups you want to sync with BMS.
  3. In BMS, click Add under the Mapping Rules tab.
  4. Complete the pop-up form, and click Save.
  5. Go to the Microsoft Entra Connections tab and click Sync.
  6. You can now navigate to CRM > Contacts or HR > Employees to view synced records.

mceclip12.png